# Pegasus Mail Mail Merge Extension

This extension lets you create personalised electronic mail messages using a data file and a format file.

	The data file
	The format file
	Message options
	Performing a merge

#$ The data file

The data file contains the information unique to each message in the merge process. It is also a text file, but it must be formatted a special way. Each line in the data file contains a single record, or enough information to generate one complete personalised message. The record should be divided into separate fields, each containing one discrete piece of information that can be placed in your message. Each field in the record must be separated from the next field by a special separator character - the <Tab> character is commonly used for this purpose, but the extension will allow you to use any character or set of characters as a separator. The data file will usually be generated by a database application, but if you wish you can also create it using a text editor or word processor, provided you format it correctly and save it as a text file.

Each record in the data file must have the same number of fields, and the fields must appear in the same order in each record. One field in each record must contain the e-mail address to which the merged message should be sent - this can be any address you might normally use in a Pegasus Mail message, including aliases from your address book and NetWare groups.

Example

You want to send two messages, one to Janet@foo.bar, and one to John@snafu.org. In each message, you want to have a salutation ("Dear XXXX"), and a reminder of the other's birthday, separated by commas. The data file might look like this:

janet@foo.bar,Janet,17th of September
john@snafu.org,John,3rd of July

When you use this data file, the placeholder "~2~" in the format file will be replaced by the recipient's name (e.g, "Dear Janet") and the placeholder "~3~" will be replaced by the other person's birthday (e.g, "Don't forget the 17th of September!"). You will tell the mail merge extension that the e-mail address is contained in field 1.

#$ The format file

The format file contains the invariant part of the mail merge: the information in this file appears in every message generated from a merge. It is a simple text file containing the information you want to send, along with special placeholder characters that show where the information from the data file should be placed. You can create this file in any text editor (such as the Windows Notepad utility) or in any word processor, provided you remember to save the file as plain text.

Placeholders: placeholders are special markers that tell the Mail Merge Extension where information from the data file should be placed in the merged message. A placeholder consists of one or two characters surrounded by tilde characters ('~'). A placeholder containing a number between 1 and 32 indicates that the information from that field in the current record in the data file should be written into the merged message. To write a single tilde character into your merged message, enter two tildes together - like this: "~~".

Example:

The current data record is:
	janet@foo.bar,Janet,17th of September

The format file:
	"Dear ~2~, Please don't forget the ~3~."

Would result in the message:

	"Dear Janet, Please don't forget the 17th of September."

#$ Message options

You can set certain common options for messages generated by a mail merge: these options appear in the bottom pane of the MailMerge Extension's Window.

Subject  The subject for the message. The same subject is used for every message generated by the merge, so you should keep it as generic as possible.

Copy self  If checked, Pegasus Mail will keep a copy of each message resulting from the merge. You should be careful of this option, especially if you are performing large merge operations, since you will get one copy to self for each message sent.

Urgent  If checked, the message will be sent as urgent. Remember that many people find urgent mail rude and intrusive - use this option sparingly for maximum effect.

Confirm reading  If checked, Pegasus Mail will request confirmation of reading for each message generated by the merge. You will only get a confirmation of reading from other users with Pegasus Mail, and only if they permit it. Remember that this option affects every message generated by the merge, so if you are performing large merges, you may get a great many confirmations of reading in return.

Use MIME  MIME is a special Internet message format that allows the preservation of International characters. If you know that the majority of the people to whom you are sending mail are using Pegasus Mail or some other MIME-compliant mail system, you should check this control.

#$ Performing a merge

To perform a mail merge, follow these steps:

1:	Prepare your format file, making sure that the placeholders are where you expect them to be.

2:	Prepare your data file, usually by exporting information from your database application as a delimited text file.

3:	Start the MailMerge Extension from within Pegasus Mail by double-clicking on its entry in the Extension Manager window.

4:	Enter the name of the data file you created in step 2 in the Data file field. You can use the "?" button to browse your hard disk or network for the file if you wish.

5:	If the fields in your data file are separated by <Tab> characters, make sure the Tabs control is checked, otherwise make sure the Other control is checked and enter the separator character or characters in the edit field.

6:	In the The e-mail address is field number field enter the number of the field that contains the e-mail address for each record in your data file.

7:	In the Formatting file field, enter the name of the format file you prepared in step 1. As with entering the data file, you can click the "?" button to browse your hard disk for the file.

8:	In the Message options panel, enter a subject for the merged message and check any of the message feature controls you want to use (make sure you've read the warnings about some of these controls in the Message Options section of this file before using them).

9:	Click the Send button; Pegasus Mail will merge the data and format files, and will send out the resulting messages for you. Any errors in formatting or in data entry will be reported to you at this time.